WonderLeak Help: Integration - Application Programming Interface

The WonderLeak application programming interface (API) is exposed to target applications via the WonderLeakAPI.h header file and is suitable for use in C/C++ projects. This file is located in the WonderLeak application installation folder, typically located at C:\Program Files\WonderLeak\include\WonderLeakAPI.h. Include this file in your project to be able to call the API functions.

When a target application is profiled by WonderLeak, a DLL WonderLeakHook64.dll for 64-bit (x64) targets or WonderLeakHook32.dll for 32-bit (x86) targets is loaded into the target process. This DLL performs the profiling and exposes the API to the target application. An environment variable WONDERLEAK=1 will be defined for an application being profiled by WonderLeak.

WonderLeakAPI_Snapshot

Take a snapshot of all current allocations in the current process.

int WonderLeakAPI_SnapshotW(
    const wchar_t* name = NULL,
    DWORD tid = WONDERLEAK_TID_ANY
);

int WonderLeakAPI_SnapshotA(
    const char* name = NULL,
    DWORD tid = WONDERLEAK_TID_ANY
);

#if defined(UNICODE) || defined(_UNICODE)
#define WonderLeakAPI_Snapshot  WonderLeakAPI_SnapshotW
#else
#define WonderLeakAPI_Snapshot  WonderLeakAPI_SnapshotA
#endif

Parameters

name: An optional name for this new snapshot.
tid: An optional parameter. Only capture allocations originating from the thread ID specified. If the thread ID is WONDERLEAK_TID_CURRENT (0) only allocations originating from the current thread will be captured. If the thread ID is WONDERLEAK_TID_ANY (-1) all allocations originating from all threads will be captured.

Return value

The return value will be WONDERLEAK_API_SUCCESS (0) upon success or WONDERLEAK_API_FAILURE (-1) upon failure.

WonderLeakAPI_SetThreadName

Associate a name with a thread. This name will be displayed in the WonderLeak UI.

int WonderLeakAPI_SetThreadNameW(
    const wchar_t* name,
    DWORD tid = WONDERLEAK_TID_CURRENT
);

int WonderLeakAPI_SetThreadNameA(
    const char* name, 
    DWORD tid = WONDERLEAK_TID_CURRENT
);

#if defined(UNICODE) || defined(_UNICODE)
#define WonderLeakAPI_SetThreadName  WonderLeakAPI_SetThreadNameW
#else
#define WonderLeakAPI_SetThreadName  WonderLeakAPI_SetThreadNameA
#endif

Parameters

name: A name for the thread.
tid: An optional parameter. The thread ID of the thread to name, or WONDERLEAK_TID_CURRENT (0) to name the current thread.

Return value

The return value will be WONDERLEAK_API_SUCCESS (0) upon success or WONDERLEAK_API_FAILURE (-1) upon failure.

WonderLeakAPI_IgnoreHeapAllocation

Tag a heap allocation as ignore. The allocation will still be recorded by WonderLeak but it will now have the 'ignore' hint associated with it. This allows filter rules to include or exclude such allocations.

int WonderLeakAPI_IgnoreHeapAllocation(
    void* ptr
);

Parameters

ptr: The pointer to the allocated heap chunk as returned by any heap allocator that supports being profiled.

Return value

The return value will be WONDERLEAK_API_SUCCESS (0) upon success or WONDERLEAK_API_FAILURE (-1) upon failure.

WonderLeakAPI_UserHeapCreate

Create a new heap which can service allocations via WonderLeakAPI_UserHeapAllocate, WonderLeakAPI_UserHeapReAllocate, WonderLeakAPI_UserHeapFree and WonderLeakAPI_UserHeapSize. All serviced allocations are traced by WonderLeak. User heaps allow a developer to support tracing allocations for custom allocators that may not be supported by WonderLeak. All allocations can be serviced by the above functions when WonderLeak is profiling. A custom heap name will help identify these allocations when reviewing the profiled snapshots.

userheap_id WonderLeakAPI_UserHeapCreateW(
    const wchar_t* name
);

userheap_id WonderLeakAPI_UserHeapCreateA(
    const char* name
);

#if defined(UNICODE) || defined(_UNICODE)
#define WonderLeakAPI_UserHeapCreate  WonderLeakAPI_UserHeapCreateW
#else
#define WonderLeakAPI_UserHeapCreate  WonderLeakAPI_UserHeapCreateA
#endif

Parameters

name: A name for this heap to identify it within WonderLeak

Return value

On success, the return value will be a unique userheap_id value for this heap. On failure, the return value will be 0.

WonderLeakAPI_UserHeapAllocate

Allocate a chunk of memory from a user heap. This allocation will be traced by WonderLeak.

void* WonderLeakAPI_UserHeapAllocate(
    userheap_id id, 
    size_t sz
);

Parameters

id: The unique userheap_id for the heap which will service the allocation.
sz: The size in bytes of the chunk to allocate.

Return value

On success a pointer to the allocated chunk will be returned. On failure a value of 0 will be returned.

WonderLeakAPI_UserHeapReAllocate

Reallocates a chunk of memory from a user heap previously allocated via WonderLeakAPI_UserHeapAllocate or WonderLeakAPI_UserHeapReAllocate.

void* WonderLeakAPI_UserHeapReAllocate(
    userheap_id id, 
    void* ptr,
    size_t sz
);

Parameters

id: The unique userheap_id for the heap which will service the reallocation.
ptr: The pointer to a previously allocated chunk.
sz: The size in bytes to reallocate the chunk.

Return value

On success a pointer to the reallocated chunk will be returned. On failure a value of 0 will be returned.

WonderLeakAPI_UserHeapFree

Frees a chunk of memory from a user heap.

void WonderLeakAPI_UserHeapFree(
    userheap_id id, 
    void* ptr
);

Parameters

id: The unique userheap_id for the heap which will service the free.
ptr: A pointer to an allocated chunk.

Return value

None.

WonderLeakAPI_UserHeapSize

Query a user heap for the size of an allocated chunk.

size_t WonderLeakAPI_UserHeapSize(
    userheap_id id, 
    void* ptr
);

Parameters

id: The unique userheap_id for the heap which allocated the chunk.
ptr: A pointer to an allocated chunk.

Return value

On success the size in bytes of the allocated chunk. On failure a value of -1 will be returned.

WonderLeakAPI_UserHandlesCreate

Unlike a heap allocation which makes available a linear sequence of bytes, a handle allocation is a unique ID to an associated resource. WonderLeak exposes several functions to profile resource allocations within your application which are encapsulated by handles. To profile a handle allocation you must first create a userhandles_id for the group of handles you wish to profile. Once created you can record allocating and freeing handles to and from this group.

userhandles_id WonderLeakAPI_UserHandlesCreateW(
    const wchar_t* name
);

userhandles_id WonderLeakAPI_UserHandlesCreateA(
    const char* name
);

#if defined(UNICODE) || defined(_UNICODE)
#define WonderLeakAPI_UserHandlesCreate  WonderLeakAPI_UserHandlesCreateW
#else
#define WonderLeakAPI_UserHandlesCreate  WonderLeakAPI_UserHandlesCreateA
#endif

Parameters

name: A name for this handle group to identify it within WonderLeak.

Return value

On success, the return value will be a unique userhandles_id value for this handle group. The handle group must be destroyed via WonderLeakAPI_UserHandlesDestroy. On failure, the return value will be 0.

WonderLeakAPI_UserHandlesAllocate

Record the allocation of a handle to a handle group.

void WonderLeakAPI_UserHandlesAllocate(
    userhandles_id id, 
    void* handle
);

Parameters

id: A unique userhandles_id for a handle group.
handle: The handle value you wish to allocate to this handle group.

Return value

None.

WonderLeakAPI_UserHandlesFree

Record the freeing of a handle from a handle group.

void WonderLeakAPI_UserHandlesFree(
    userhandles_id id, 
    void* handle
)

Parameters

id: A unique userhandles_id for a handle group.
handle: The handle value you wish to free from this handle group.

Return value

None.